/**
 * Notes: API数据类型定义
 * Ver : WeCollege Server API 1.0.0
 * Date: 2025-01-27
 * Description: 定义所有API请求和响应的数据结构
 */

// ==================== 通用数据结构 ====================

/**
 * 通用响应结构
 * @typedef {Object} ApiResponse
 * @property {number} code - 响应码
 * @property {string} msg - 响应消息
 * @property {*} data - 响应数据
 */

/**
 * 分页查询基础结构
 * @typedef {Object} PageQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 */

/**
 * 分页响应结构
 * @typedef {Object} PageResponse
 * @property {number} total - 总数
 * @property {number} pages - 总页数
 * @property {Array} list - 数据列表
 */

// ==================== 用户认证相关 ====================

/**
 * 用户登录请求
 * @typedef {Object} UserLoginDTO
 * @property {string} code - 微信登录code
 */

/**
 * 用户登录响应
 * @typedef {Object} UserLoginVO
 * @property {number} id - 用户ID
 * @property {string} openid - 微信openid
 * @property {string} token - 认证token
 */

// ==================== 帖子相关 ====================

/**
 * 帖子发布请求
 * @typedef {Object} PostDto
 * @property {string} title - 标题
 * @property {string} content - 内容
 * @property {string} typeId - 分类ID
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 */

/**
 * 帖子查询请求
 * @typedef {Object} PostQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 * @property {string} typeId - 分类ID
 * @property {string} str - 搜索字符串
 */

/**
 * 帖子实体
 * @typedef {Object} Post
 * @property {number} createTimestamp - 创建时间戳
 * @property {number} updateTimestamp - 更新时间戳
 * @property {string} createUserId - 创建用户ID
 * @property {string} updateUserId - 更新用户ID
 * @property {number} version - 版本号
 * @property {string} postId - 帖子ID
 * @property {string} title - 标题
 * @property {string} content - 内容
 * @property {string} userId - 用户ID
 * @property {string} typeId - 分类ID
 * @property {number} likeNum - 点赞数
 * @property {number} visitNum - 访问数
 * @property {number} subNum - 订阅数
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {number} commentNum - 评论数
 */

/**
 * 帖子展示对象
 * @typedef {Object} PostVo
 * @property {string} postId - 帖子ID
 * @property {string} title - 标题
 * @property {string} content - 内容
 * @property {string} userId - 用户ID
 * @property {string} createTimestamp - 创建时间
 * @property {string} updateTimestamp - 更新时间
 * @property {string} typeId - 分类ID
 * @property {number} visitNum - 访问数
 * @property {number} subNum - 订阅数
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} image - 用户头像
 * @property {string} nickName - 用户昵称
 * @property {number} like - 点赞状态
 */

// ==================== 评论相关 ====================

/**
 * 评论请求
 * @typedef {Object} CommentDto
 * @property {string} lastId - 回复用户ID
 * @property {string} postId - 帖子ID
 * @property {string} lastCommentId - 回复评论ID
 * @property {string} content - 评论内容
 */

/**
 * 评论查询请求
 * @typedef {Object} CommentQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 * @property {string} postId - 帖子ID
 * @property {string} lastEndKey - 最后结束键
 * @property {string} endCommentId - 结束评论ID
 */

/**
 * 评论展示对象
 * @typedef {Object} CommentVo
 * @property {string} commentId - 评论ID
 * @property {string} postId - 帖子ID
 * @property {string} userId - 用户ID
 * @property {string} image - 用户头像
 * @property {string} nickName - 用户昵称
 * @property {string} content - 评论内容
 * @property {Array<SubCommentVo>} subComments - 子评论列表
 * @property {number} likeNum - 点赞数
 * @property {string} createTime - 创建时间
 * @property {number} subCount - 子评论数量
 * @property {boolean} liked - 是否已点赞
 */

/**
 * 子评论展示对象
 * @typedef {Object} SubCommentVo
 * @property {string} commentId - 评论ID
 * @property {string} postId - 帖子ID
 * @property {string} userId - 用户ID
 * @property {string} image - 用户头像
 * @property {string} nickName - 用户昵称
 * @property {string} content - 评论内容
 * @property {string} createTime - 创建时间
 * @property {string} lastId - 回复用户ID
 * @property {string} lastNick - 回复用户昵称
 * @property {boolean} liked - 是否已点赞
 */

// ==================== 失物招领相关 ====================

/**
 * 失物发布请求
 * @typedef {Object} LostDto
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} type - 类型
 */

/**
 * 失物更新请求
 * @typedef {Object} LostUpdateDto
 * @property {string} lostId - 失物ID
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 */

/**
 * 失物查询请求
 * @typedef {Object} LostQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 * @property {string} str - 搜索字符串
 * @property {number} type - 类型
 */

/**
 * 失物实体
 * @typedef {Object} Lost
 * @property {number} createTimestamp - 创建时间戳
 * @property {number} updateTimestamp - 更新时间戳
 * @property {string} createUserId - 创建用户ID
 * @property {string} updateUserId - 更新用户ID
 * @property {number} version - 版本号
 * @property {string} lostId - 失物ID
 * @property {string} userId - 用户ID
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} type - 类型
 */

// ==================== 交易相关 ====================

/**
 * 商品发布请求
 * @typedef {Object} TradeDto
 * @property {number} price - 价格
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} area - 区域
 * @property {string} buildings - 楼栋
 * @property {string} type - 类型
 */

/**
 * 商品更新请求
 * @typedef {Object} TradeUpdateDto
 * @property {string} tradeId - 商品ID
 * @property {number} price - 价格
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} area - 区域
 * @property {string} buildings - 楼栋
 */

/**
 * 商品查询请求
 * @typedef {Object} TradeQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 */

/**
 * 主页商品查询请求
 * @typedef {Object} MainTradeQuery
 * @property {number} pageNo - 页码
 * @property {number} pageSize - 每页数量
 * @property {string} sortBy - 排序字段
 * @property {boolean} isAsc - 是否升序
 * @property {string} endKey - 结束键
 * @property {number} startTimestamp - 开始时间戳
 * @property {number} area - 区域
 * @property {string} buildings - 楼栋
 * @property {string} match - 匹配字符串
 * @property {number} minPrice - 最低价格
 * @property {number} maxPrice - 最高价格
 * @property {number} type - 类型
 */

/**
 * 商品实体
 * @typedef {Object} Trade
 * @property {number} createTimestamp - 创建时间戳
 * @property {number} updateTimestamp - 更新时间戳
 * @property {string} createUserId - 创建用户ID
 * @property {string} updateUserId - 更新用户ID
 * @property {number} version - 版本号
 * @property {string} tradeId - 商品ID
 * @property {string} userId - 用户ID
 * @property {number} price - 价格
 * @property {string} title - 标题
 * @property {string} description - 描述
 * @property {string} pic1 - 图片1
 * @property {string} pic2 - 图片2
 * @property {string} pic3 - 图片3
 * @property {string} area - 区域
 * @property {string} buildings - 楼栋
 * @property {number} visitNum - 访问数
 * @property {number} wantNum - 想要数
 * @property {string} type - 类型
 */

// ==================== 通用类型 ====================

/**
 * 分类类型
 * @typedef {Object} Type
 * @property {number} createTimestamp - 创建时间戳
 * @property {number} updateTimestamp - 更新时间戳
 * @property {string} createUserId - 创建用户ID
 * @property {string} updateUserId - 更新用户ID
 * @property {number} version - 版本号
 * @property {string} typeId - 分类ID
 * @property {string} name - 分类名称
 */

/**
 * 轮播图
 * @typedef {Object} BackgroundVo
 * @property {number} sort - 排序
 * @property {string} image - 图片地址
 * @property {string} link - 链接地址
 * @property {string} createTime - 创建时间
 */

// 导出类型定义 (仅用于文档，JavaScript运行时不使用)
module.exports = {
  // 这里可以导出一些类型验证函数或默认值
  DEFAULT_PAGE_SIZE: 20,
  DEFAULT_PAGE_NO: 1,
  
  // 验证函数示例
  validatePageQuery: (query) => {
    return {
      pageNo: query.pageNo || 1,
      pageSize: query.pageSize || 20,
      sortBy: query.sortBy || '',
      isAsc: query.isAsc || false,
      endKey: query.endKey || '',
      startTimestamp: query.startTimestamp || 0
    };
  }
};